Working With Times2

The Movie Toolbox provides a number of functions that allow you to work with time structures. This section describes those functions.

All of these functions work with time structures (see "The Time Structure" for a complete discussion of the time structure). You can use time structures to represent either time values or durations. Time values specify a point in time, relative to a given time base. Durations specify a span of time, relative to a given time scale. Durations are represented by time structures that have the time base set to 0 (that is, the base field in the time structure is set to nil ).

You can use the ConvertTime function to convert a time you obtain from one time base into a time that is relative to another time base. Similarly, you can use the ConvertTimeScale function to convert a time from one time scale to another.

You can add two times by calling the AddTime function; you can subtract two times with the SubtractTime function.

AddTime

The AddTime function adds two times. You must specify the times in time structures.



 
pascal void AddTime  (TimeRecord *dst, const TimeRecord *src);

dst: Contains a pointer to a time structure. This time structure contains one of the operands for the addition. The AddTime function returns the result of the addition into this time structure.
src: Contains a pointer to a time structure. The Movie Toolbox adds this value to the time or duration specified by the dst parameter.

DESCRIPTION

If these times are relative to different time scales or time bases, the AddTime function converts the times as appropriate to yield reasonable results. However, the time bases for both time values must rely on the same time source.

The result value is formatted based on the operands as follows:

`dst`	`src`	Result
Duration	Duration	Duration
Time value	Duration	Time value

ERROR CODES

None

SubtractTime

The SubtractTime function subtracts one time from another. You must specify the times in time structures.



 
pascal void SubtractTime (TimeRecord *dst, const TimeRecord *src);

dst: Contains a pointer to a time structure. This time structure contains one of the operands for the subtraction. The SubtractTime function returns the result of the subtraction into this time structure.
src: Contains a pointer to a time structure. The Movie Toolbox subtracts this value from the time or duration specified by the dst parameter.

DESCRIPTION

If these times are relative to different time scales or time bases, the SubtractTime function converts the times as appropriate to yield reasonable results. However, the time bases for both time values must rely on the same time source.

The result value is formatted based on the operands as follows:

`dst`	`src`	Result
Time value	Duration	Duration
Duration	Duration	Duration
Time value	Time value	Duration

ERROR CODES

None

ConvertTime

You can convert a time you obtain from one time base into a time that is relative to another time base by calling the ConvertTime function. Both time bases must rely on the same time source. You must specify the time to be converted in a time structure.



 
pascal void ConvertTime (TimeRecord *inout, TimeBase newBase);

inout: Contains a pointer to a time structure that contains the time value to be converted. The ConvertTime function replaces the contents of this time structure with the time value relative to the specified time base.
newBase: Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

DESCRIPTION

The ConvertTime function includes the rate associated with each time value in the conversion; therefore, you should use this function when you want to convert time values. Use the ConvertTimeScale function (described in the next section) to convert durations.

ERROR CODES

None

ConvertTimeScale

You can convert a time from one time scale into a time that is relative to another time base by calling the ConvertTimeScale function. You must specify the time to be converted in a time structure.



 
pascal void ConvertTimeScale (TimeRecord *inout, 

                                         TimeScale newScale);

inout: Contains a pointer to a time structure that contains the time value to be converted. The ConvertTimeScale function replaces the contents of this time structure with the time value relative to the specified time scale.
newScale: Specifies the time scale for this operation.

DESCRIPTION

The ConvertTimeScale function does not include the rate associated with the time value in the conversion; therefore, you should use this function when you want to convert time durations, but not when converting time values. Use the ConvertTime function (described in the previous section) to convert time values.

ERROR CODES

None